Upload Media Assets

Introduction

Upload custom media assets to JoggAI to enhance your videos. Include branded images, product photos, background videos, custom audio, and more in your video creation projects.

Key Features

Multiple Formats

Support for images, videos, and audio

Easy Integration

Reference assets by ID in video creation

Organized Storage

Organize assets into folders

Reusable Assets

Upload once, use in multiple projects

Workflow Overview

Get Signed URL

Request upload URL with file metadata

Upload File

Upload file using PUT request to signed URL

Use Asset URL

Use asset_url from Step 1 in video creation

Assets are stored permanently and can be reused across multiple video projects.

Quick Start

Endpoint	Purpose	Documentation
`POST /upload/asset`	Upload media file	API Reference
`POST /create_video_from_avatar`	Use assets in videos	API Reference

Key Parameters

Parameter	Type	Required	Description
`filename`	string	✅	Name of the file to upload
`content_type`	string	✅	MIME type (e.g., “image/jpeg”, “video/mp4”, “audio/mpeg”)
`file_size`	integer	❌	File size in bytes (optional)

Code Examples

Scenario 1: Upload Image

Upload product photos, logos, or background images: Step 1: Get Signed URL

curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "product.jpg",
    "content_type": "image/jpeg",
    "file_size": 245678
  }'

Response:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/img_abc123.jpg"
  }
}

Step 2: Upload File Using PUT

curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: image/jpeg' \
  --data-binary '@/path/to/product.jpg'

After successful PUT upload, use the asset_url from Step 1 response in your video creation requests.

Supported Image Formats:

Format	Max Size	Best For
JPG	10MB	Photos, product images
PNG	10MB	Images with transparency
WebP	10MB	Modern, efficient format
GIF	10MB	Animated images

Recommended resolution: 1920x1080 or higher

Scenario 2: Upload Video

Upload background videos or product demos: Step 1: Get Signed URL

curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "demo.mp4",
    "content_type": "video/mp4",
    "file_size": 8456789
  }'

Response:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/vid_def456.mp4"
  }
}

Step 2: Upload File Using PUT

curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: video/mp4' \
  --data-binary '@/path/to/demo.mp4'

Supported Video Formats:

Format	Max Size	Max Duration	Best For
MP4	100MB	5 minutes	Best compatibility
WebM	100MB	5 minutes	Web optimized
MOV	100MB	5 minutes	High quality

Videos longer than 5 minutes will be rejected. Codec: H.264/H.265

Scenario 3: Upload Audio

Upload custom voiceovers or background music: Step 1: Get Signed URL

curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "music.mp3",
    "content_type": "audio/mpeg",
    "file_size": 3456789
  }'

Response:

{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/aud_ghi789.mp3"
  }
}

Step 2: Upload File Using PUT

curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/music.mp3'

Supported Audio Formats:

Format	Max Size	Max Duration	Best For
MP3	20MB	10 minutes	Best compatibility
WAV	20MB	10 minutes	Highest quality
M4A	20MB	10 minutes	Good quality, small size

Recommended: MP3 at 192 kbps for music, 128 kbps for voice

Scenario 4: Use Uploaded Assets in Video

Reference uploaded assets in video creation:

curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar_id": 81,
    "avatar_type": 0,
    "voice_id": "en-US-ChristopherNeural",
    "script": "Check out our amazing product!",
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "background_image": "img_abc123",
    "background_music": "aud_ghi789"
  }'

Use asset_id values to reference your uploaded assets in any video creation endpoint.

Format Specifications

Images

Recommended Settings:

Resolution: 1920x1080 (1080p) or higher
Quality: 80-90% for JPG
Format: JPG for photos, PNG for transparency

Optimization:

# Using ImageMagick
convert input.jpg -resize 1920x1080 -quality 85 output.jpg

# Using FFmpeg for WebP
ffmpeg -i input.jpg -q:v 80 output.webp

Videos

Recommended Settings:

Resolution: 1920x1080 (1080p)
Codec: H.264
Bitrate: 5-8 Mbps
Frame Rate: 24, 30, or 60 fps
Audio: AAC, 192 kbps

Optimization:

# Using FFmpeg
ffmpeg -i input.mp4 \
  -vcodec h264 \
  -crf 23 \
  -preset medium \
  -vf scale=1920:1080 \
  -acodec aac \
  -b:a 192k \
  output.mp4

Audio

Recommended Settings:

Music: MP3, 192-256 kbps, Stereo
Voice: MP3, 128-192 kbps, Mono
Sample Rate: 44.1 kHz

Optimization:

# Convert to MP3 at 192kbps
ffmpeg -i input.wav -codec:a libmp3lame -b:a 192k output.mp3

# Normalize audio levels
ffmpeg -i input.mp3 -filter:a loudnorm output.mp3

Use Case Examples

E-commerce Product Videos

Upload product images and demo videos:

Product photos in multiple angles
Usage demonstration videos
Brand logos and watermarks
Background music for product showcases

Corporate Videos

Create professional corporate content:

Company logos and branding
Office or facility videos
Employee photos
Corporate audio branding

Social Media Content

Educational Content

Enhance learning materials:

Diagrams and charts
Demonstration videos
Background music
Custom voiceovers

Best Practices

Before Uploading

Compress files to reduce upload time and storage
Test files locally to ensure they’re not corrupted
Use appropriate formats (JPG for photos, MP4 for videos, MP3 for audio)
Optimize quality - balance between quality and file size

Organization

Use descriptive names for easy identification
Leverage folder parameter to organize by project or type
Document asset IDs in your project management system
Maintain a local backup of original files

File Size Limits

Asset Type	Max Size	Recommendation
Images	10MB	Aim for 500KB-2MB
Videos	100MB	Aim for 20-50MB
Audio	20MB	Aim for 2-5MB

Troubleshooting

File Too Large

Error: File size exceeds limitSolutions:

Images: Reduce resolution or quality (use 80-85% quality for JPG)
Videos: Lower bitrate, reduce resolution, or shorten duration
Audio: Convert to MP3, reduce bitrate to 128-192 kbps
General: Compress before upload using tools like FFmpeg or ImageMagick

Unsupported Format

Error: File format not supportedSolutions:

Convert to supported format (JPG/PNG for images, MP4 for videos, MP3 for audio)
Check file extension matches actual format
Ensure file is not corrupted
For videos, ensure codec is H.264

Upload Failed

Error: Upload failed or timeoutSolutions:

Check internet connection stability
Verify API key is valid and has upload permissions
Ensure file path is correct
Try compressing the file first
Retry with exponential backoff

Quality Issues

Problem: Uploaded asset looks poor qualitySolutions:

Upload higher resolution original files
Don’t upscale low-resolution images
For JPG, use 85-90% quality setting
For videos, use appropriate bitrate (5-8 Mbps for 1080p)
For audio, use at least 192 kbps for music

Create Avatar Videos

Use uploaded assets in avatar videos

Product Videos

Include custom media in product videos

Template Videos

Use assets in video templates

Upload API Reference

Detailed API documentation

QuickStart

Workflows Guides

Video

Avatar

Voice

Asset

Template

Product

User

Webhook

Introduction

Key Features

Multiple Formats

Easy Integration

Organized Storage

Reusable Assets

Workflow Overview

Quick Start

Key Parameters

Code Examples

Scenario 1: Upload Image

Scenario 2: Upload Video

Scenario 3: Upload Audio

Scenario 4: Use Uploaded Assets in Video

Format Specifications

Images

Videos

Audio

Use Case Examples

Best Practices

Before Uploading

Organization

File Size Limits

Troubleshooting

Create Avatar Videos

Product Videos

Template Videos

Upload API Reference

QuickStart

Workflows Guides

Video

Avatar

Voice

Asset

Template

Product

User

Webhook

​Introduction

​Key Features

Multiple Formats

Easy Integration

Organized Storage

Reusable Assets

​Workflow Overview

​Quick Start

​Related API Endpoints

​Key Parameters

​Code Examples

​Scenario 1: Upload Image

​Scenario 2: Upload Video

​Scenario 3: Upload Audio

​Scenario 4: Use Uploaded Assets in Video

​Format Specifications

​Images

​Videos

​Audio

​Use Case Examples

​Best Practices

​Before Uploading

​Organization

​File Size Limits

​Troubleshooting

​Related Documentation

Create Avatar Videos

Product Videos

Template Videos

Upload API Reference

Introduction

Key Features

Workflow Overview

Quick Start

Related API Endpoints

Key Parameters

Code Examples

Scenario 1: Upload Image

Scenario 2: Upload Video

Scenario 3: Upload Audio

Scenario 4: Use Uploaded Assets in Video

Format Specifications

Images

Videos

Audio

Use Case Examples

Best Practices

Before Uploading

Organization

File Size Limits

Troubleshooting

Related Documentation